# List AI agent profile versions

Returns immutable profile version history for an agent.

RBAC:
- requires ANY of AIAgents.Read, AIAgents.Manage, GroupAIAgents.Read, GroupAIAgents.Manage

Endpoint: GET /api/v1/ai-agents/{agentId}/versions
Version: 1.0
Security: header

## Path parameters:

  - `agentId` (string, required)
    UUID with type prefix
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

## Query parameters:

  - `scope` (string, required)
    Scope: 'global' or group TypeId

## Response 200 fields (application/json):

  - `resourceIds` (array)
    Group scope resource ids (group channels). Empty means whole group.
    Example: ["gc_01hz1f0kw36f82k9s4nzpc4s92n"]

  - `tools` (array)
    List of tools enabled for this bot
    Enum: "VECTOR_SEARCH", "REGULAR_SEARCH", "ENTITY_SEARCH", "WEB_SEARCH", "POSTS_SINCE_LAST_INVOCATION", "POSTS_IN_TIME_RANGE", "LIST_GROUP_STRUCTURE", "REPLY", "LIKE", "REPORT", "QUOTE", "CREATE_OR_UPDATE_POST", "GENERATE_IMAGES", "REPORT_CONTENT", "ADD_REPORT_NOTE", "API_ACCESS"

  - `triggers` (array)
    Configured triggers for this bot

  - `triggers.type` (string, required)
    Trigger type
    Enum: "POST_CREATED", "REPLY_CREATED", "POST_EDITED", "MENTIONED", "QUESTION_DETECTED", "KEYWORD_MATCH", "INTENT_MATCH", "REPORTED_CONTENT", "THRESHOLD", "UNANSWERED", "CRON", "NEW_GROUP_MEMBER", "DIRECT_REPLY"

  - `triggers.prompt` (string,null)
    Optional trigger-level prompt appended to instructions when this trigger matches
    Example: "Prioritize concise replies for this trigger."

  - `modelId` (string,null)
    Model identifier (ai_models.model_id); must be enabled in this scope
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `uploadIds` (array)
    List of uploads (documents) attached to the bot
    Example: ["up_01hz1f0kw36f82k9s4nzpc4s92n"]

  - `dailyBudget` (integer,null)
    Daily budget in USD cents (null = unlimited)
    Example: 1000

  - `monthlyBudget` (integer,null)
    Monthly budget in USD cents (null = unlimited)
    Example: 10000

  - `rateLimitHourly` (integer,null)
    Maximum invocations per hour (null = unlimited)
    Example: 100

  - `rateLimitDaily` (integer,null)
    Maximum invocations per day (null = unlimited)
    Example: 1000

  - `role` (array)
    Role/instruction directives for the agent
    Example: ["Skeptical engineer"]

  - `personality` (array)
    Personality traits used when building agent instructions
    Example: ["Friendly","Fact-checking"]

  - `style` (array)
    Writing/response style directives
    Example: ["Clear paragraphs","Simple language"]

  - `behavior` (array)
    Behavior directives
    Example: ["Explain first","Ask clarifying questions"]

  - `prompt` (string,null)
    Additional free-form prompt/instructions
    Example: "Prioritize concise actionable guidance."

  - `agentId` (string, required)
    Bot user id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `groupId` (string,null)
    Group id for group-scoped bots
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `version` (integer, required)
    Immutable profile version number for this agent
    Example: 1

  - `stats` (object, required)
    Combined stats across all profile versions for the current agent state

  - `stats.runs` (integer, required)
    Total number of job invocations

  - `stats.costCents` (integer, required)
    Total cost in USD cents

  - `stats.postsCreated` (integer, required)
    Total number of posts created

  - `stats.imagesGenerated` (integer, required)
    Total number of images generated

  - `stats.runs7d` (integer, required)
    Number of job invocations in the last 7 days

  - `stats.costCents7d` (integer, required)
    Total cost in USD cents in the last 7 days

  - `stats.postsCreated7d` (integer, required)
    Number of posts created in the last 7 days

  - `stats.imagesGenerated7d` (integer, required)
    Number of images generated in the last 7 days

  - `versionStats` (object, required)
    Stats for this exact profile version

  - `versionStats.runs` (integer, required)
    Total number of job invocations

  - `versionStats.costCents` (integer, required)
    Total cost in USD cents

  - `versionStats.postsCreated` (integer, required)
    Total number of posts created

  - `versionStats.imagesGenerated` (integer, required)
    Total number of images generated

  - `enabled` (boolean, required)
    Whether this bot is enabled
    Example: true

  - `currentAt` (string,null)
    When this profile version became current (null for non-current versions)
    Example: "2022-03-10T16:15:50Z"

  - `isCurrent` (boolean, required)
    Whether this profile version is currently active

  - `createdAt` (string, required)
    ISO 8601 timestamp when this profile was created
    Example: "2022-03-10T16:15:50Z"

## Response 401 fields (application/json):

  - `errorCode` (string, required)
    Error code

  - `message` (string, required)
    Error message

  - `docUrl` (string)
    Link to documentation

## Response 403 fields (application/json):

  - `errorCode` (string, required)
    Error code

  - `message` (string, required)
    Error message

  - `docUrl` (string)
    Link to documentation

## Response 404 fields (application/json):

  - `errorCode` (string, required)
    Error code

  - `message` (string, required)
    Error message

  - `docUrl` (string)
    Link to documentation